.TH "UNICORN" "3" "Jan 19th 2025" "Unicorn 1.0.3"
.SH NAME
uni_encode \- encode a scalar value
.SH LIBRARY
Embeddable Unicode Algorithms (libunicorn, -lunicorn)
.SH SYNOPSIS
.nf
.B #include <unicorn.h>
.PP
.BI "unistat uni_encode(unichar " cp ", void *" dst ", unisize *" dst_len ", uniattr " dst_attr ");"
.fi
.SH DESCRIPTION
Encoded the Unicode scalar value \f[I]cp\f[R] into the encoding form \f[I]dst_attr\f[R] and write the resulting code units to \f[I]dst\f[R].
The code unit capacity of \f[I]dst\f[R] is specified by \f[I]dst_len\f[R].
The implementation will write the number of code units needed to encode \f[I]cp\f[R] to \f[I]dst_len\f[R] on output.
.PP
If the capacity of \f[I]dst\f[R] is insufficient, then \f[B]UNI_NO_SPACE\f[R] is returned otherwise it returns \f[B]UNI_OK\f[R].
.PP
To ensure the \f[I]dst\f[R] is sufficiently-sized, the following table lists the number of code units needed to encode any character within its respective encoding form.
.PP
.TS
allbox tab(|);
ll.
\fBEncoding Form\fR|\fBLongest Code Unit Sequence\fR
T{
UTF-8
T}|T{
4
T}
T{
UTF-16
T}|T{
2
T}
T{
UTF-32
T}|T{
1
T}
.TE
.PP
If \f[I]dst\f[R] is \f[C]NULL\f[R] and \f[I]dst_len\f[R] is zero, then the number of code units needed will be computed by the implementation and written to \f[I]dst_len\f[R] and \f[B]UNI_OK\f[R] is returned.
.SH RETURN VALUE
.TP
UNI_OK
If the character was encoded successfully.
.TP
UNI_BAD_OPERATION
If \f[I]cp\f[R] is not a Unicode scalar value, if \f[I]dst_len\f[R] is \f[C]NULL\f[R], or if \f[I]dst\f[R] is \f[C]NULL\f[R] and \f[I]dst_len\f[R] is non-zero.
.TP
UNI_NO_SPACE
If \f[C]dest\f[R] is too small.
.TP
UNI_FEATURE_DISABLED
If Unicorn was built without support for the encoding form specified by \f[I]dst_attr\f[R].
.SH SEE ALSO
.BR unistat (3),
.BR unichar (3),
.BR unisize (3),
.BR uniattr (3)
.SH AUTHOR
.UR https://railgunlabs.com
Railgun Labs
.UE .
.SH INTERNET RESOURCES
The online documentation is published on the
.UR https://railgunlabs.com/unicorn
Railgun Labs website
.UE .
.SH LICENSING
Unicorn is distributed with its end-user license agreement (EULA).
Please review the agreement for information on terms & conditions for accessing or otherwise using Unicorn and for a DISCLAIMER OF ALL WARRANTIES.
